home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / ADA / GNAT / !gcc / adainc / 6 / ads / s-taprob < prev    next >
Text File  |  1996-02-12  |  9KB  |  176 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                 GNU ADA RUNTIME LIBRARY (GNARL) COMPONENTS               --
  4. --                                                                          --
  5. --      S Y S T E M . T A S K I N G . P R O T E C T E D _ O B J E C T S     --
  6. --                                                                          --
  7. --                                  S p e c                                 --
  8. --                           (Compiler Interface)                           --
  9. --                                                                          --
  10. --                             $Revision: 1.18 $                            --
  11. --                                                                          --
  12. --    Copyright (C) 1991, 92, 93, 94, 1995 Free Software Foundation, Inc.   --
  13. --                                                                          --
  14. -- GNARL is free software; you can  redistribute it  and/or modify it under --
  15. -- terms of the  GNU General Public License as published  by the Free Soft- --
  16. -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  17. -- sion. GNARL is distributed in the hope that it will be useful, but WITH- --
  18. -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  19. -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  20. -- for  more details.  You should have  received  a copy of the GNU General --
  21. -- Public License  distributed with GNARL; see file COPYING.  If not, write --
  22. -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  23. -- MA 02111-1307, USA.                                                      --
  24. --                                                                          --
  25. -- As a special exception,  if other files  instantiate  generics from this --
  26. -- unit, or you link  this unit with other files  to produce an executable, --
  27. -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  28. -- covered  by the  GNU  General  Public  License.  This exception does not --
  29. -- however invalidate  any other reasons why  the executable file  might be --
  30. -- covered by the  GNU Public License.                                      --
  31. --                                                                          --
  32. -- GNARL was developed by the GNARL team at Florida State University. It is --
  33. -- now maintained by Ada Core Technologies Inc. in cooperation with Florida --
  34. -- State University (http://www.gnat.com).                                  --
  35. --                                                                          --
  36. ------------------------------------------------------------------------------
  37.  
  38. --  Note: the compiler generates direct calls to this interface, via Rtsfind.
  39. --  Any changes to this interface may require corresponding compiler changes.
  40.  
  41. with Ada.Exceptions;
  42. --  Used for, Exception_Id
  43.  
  44. package System.Tasking.Protected_Objects is
  45.    --  This interface is described in the document
  46.    --  Gnu Ada Runtime Library Interface (GNARLI).
  47.  
  48.    pragma Elaborate_Body (System.Tasking.Protected_Objects);
  49.  
  50.    procedure Initialize_Protection
  51.      (Object            : access Protection;
  52.       Ceiling_Priority  : Integer;
  53.       Compiler_Info     : System.Address;
  54.       Entry_Bodies      : access Protected_Entry_Body_Array);
  55.    --  Initialize the Object parameter so that it can be used by the runtime
  56.    --  to keep track of the runtime state of a protected object.
  57.  
  58.    procedure Lock (Object : access Protection);
  59.    --  Lock a protected object for write access.  Upon return, the caller
  60.    --  owns the lock to this object, and no other call to Lock or
  61.    --  Lock_Read_Only with the same argument will return until the
  62.    --  corresponding call to Unlock has been made by the caller.
  63.  
  64.    procedure Lock_Read_Only (Object : access Protection);
  65.    --  Lock a protected object for read access.  Upon return, the caller
  66.    --  owns the lock for read access, and no other calls to Lock
  67.    --  with the same argument will return until the corresponding call
  68.    --  to Unlock has been made by the caller.  Other cals to Lock_Read_Only
  69.    --  may (but need not) return before the call to Unlock, and the
  70.    --  corresponding callers will also own the lock for read access.
  71.  
  72.    procedure Unlock (Object : access Protection);
  73.    --  Relinquish ownership of the lock for the object represented by
  74.    --  the Object parameter.  If this ownership was for write access, or
  75.    --  if it was for read access where there are no other read access
  76.    --  locks outstanding, one (or more, in the case of Lock_Read_Only)
  77.    --  of the tasks waiting on this lock (if any) will be given the
  78.    --  lock and allowed to return from the Lock or Lock_Read_Only call.
  79.  
  80.    procedure Protected_Entry_Call
  81.      (Object    : access Protection;
  82.       E         : Protected_Entry_Index;
  83.       Uninterpreted_Data : System.Address;
  84.       Mode      : Call_Modes;
  85.       Block     : out Communication_Block);
  86.    --  Make a protected entry call to the specified object.
  87.    --  Pend a protected entry call on the protected object represented
  88.    --  by Object.  A pended call is not queued; it may be executed immediately
  89.    --  or queued, depending on the state of the entry barrier.
  90.    --  E---The index representing the entry to be called.
  91.    --  Uninterpreted_Data---This will be returned by Next_Entry_Call
  92.    --   when this call is serviced.  It can be used by the compiler
  93.    --   to pass information between the caller and the server, in particular
  94.    --   entry parameters.
  95.    --  Mode---The kind of call to be pended.
  96.    --  Block---Information passed between one runtime call and another
  97.    --   by the compiler.
  98.  
  99.    procedure Service_Entries (Object : access Protection);
  100.    --  Service all entry queues of the specified object, executing the
  101.    --  corresponding bodies of any queued entry calls that are waiting
  102.    --  on True barriers.  This is used when the state of a protected
  103.    --  object may have changed, in particular after the execution of
  104.    --  the statement sequence of a protected procedure.
  105.    --  Note that servicing an entry may change the value of one or more
  106.    --  barriers, so this this routine keeps checking barriers until all of
  107.    --  them are closed.
  108.    --  This must be called with abortion deferred and with the corresponding
  109.    --  object locked.
  110.  
  111.    pragma Inline (Service_Entries);
  112.    --  !!! To try to be fairer to the callback interface.
  113.  
  114.    procedure Cancel_Protected_Entry_Call (Block : in out Communication_Block);
  115.    --  Attempt to cancel the most recent protected entry call.  If the call is
  116.    --  not queued abortably, wait until it is or until it has completed.
  117.    --  If the call is actually cancelled, the called object will be
  118.    --  locked on return from this call. Get_Cancelled (Block) can be
  119.    --  used to determine if the cancellation took place; there
  120.    --  may be entries needing service in this case.
  121.    --  Block passes information between this and other runtime calls.
  122.  
  123.    procedure Complete_Entry_Body (Object : access Protection);
  124.    --  Called from within an entry body procedure, indicates that the
  125.    --  corresponding entry call has been serviced.
  126.  
  127.    procedure Exceptional_Complete_Entry_Body
  128.      (Object : access Protection;
  129.       Ex     : Ada.Exceptions.Exception_Id);
  130.    --  Perform all of the functions of Complete_Entry_Body.  In addition,
  131.    --  report in Ex the exception whose propagation terminated the entry
  132.    --  body to the runtime system.
  133.  
  134.    function Enqueued (Block : Communication_Block) return Boolean;
  135.    --  Returns True if the Protected_Entry_Call which returned the
  136.    --  specified Block object was queued; False otherwise.
  137.  
  138.    function Cancelled (Block : Communication_Block) return Boolean;
  139.    --  Returns True if the Protected_Entry_Call which returned the
  140.    --  specified Block object was cancelled, False otherwise.
  141.  
  142.    procedure Requeue_Protected_Entry
  143.      (Object     : access Protection;
  144.       New_Object : access Protection;
  145.       E          : Protected_Entry_Index;
  146.       With_Abort : Boolean);
  147.    --  If Object = New_Object, queue the protected entry call on Object
  148.    --   currently being serviced on the queue corresponding to the entry
  149.    --   represented by E.
  150.    --  If Object /= New_Object, transfer the call to New_Object.E,
  151.    --   executing or queuing it as appropriate.
  152.    --  With_Abort---True if the call is to be queued abortably, false
  153.    --   otherwise.
  154.  
  155.    procedure Requeue_Task_To_Protected_Entry
  156.      (New_Object : access Protection;
  157.       E          : Protected_Entry_Index;
  158.       With_Abort : Boolean);
  159.    --  Transfer task entry call currently being serviced to entry E
  160.    --   on New_Object.
  161.    --  With_Abort---True if the call is to be queued abortably, false
  162.    --   otherwise.
  163.  
  164.    function Protected_Count
  165.      (Object : Protection;
  166.       E      : Protected_Entry_Index)
  167.       return   Natural;
  168.    --  Return the number of entry calls to E on Object.
  169.  
  170.    function Protected_Entry_Caller (Object : Protection) return Task_ID;
  171.    --  Return value of E'Caller, where E is the protected entry currently
  172.    --  being handled.  This will only work if called from within an
  173.    --  entry body, as required by the LRM (C.7.1(14)).
  174.  
  175. end System.Tasking.Protected_Objects;
  176.